How to Create Type-Ahead Query Suggestions

Note: Before continuing, familiarize yourself with the information in the topic How to Customize Your SmartHub User Interface.

What is TypeAhead?

TypeAhead is a customizable suggestion box that appears when a user begins to type a query into SmartHub.

Example of TypeAhead Suggestion Box

An example of TypeAhead suggestions in the SmartHub UI is shown below.

  • Suggestions box rendered by TypeAhead
    • This box is represented by a two-dimensional grid over which the user can define a suggestions block, which is called a section.
  • Each suggestion provider is defined under modules > TypeAhead > Providers
    • Each provider must subscribe to the Get Suggestions event that is triggered by TypeAhead.
  • When TypeAhead triggers the Get Suggestions event
    • Each provider can send suggestions asynchronously by using the callback provided by the event.
  • When TypeAhead triggers 'typeAheadResultsRendered' event
    • After suggestions box is rendered by TypeAhead, typeAheadResultsRendered event is generated.

How to Configure TypeAhead

TypeAhead, like all SmartHub modules, has settings stored in the file DefaultModuleSettings.js, which stores all the loadable components for the module.

To use (and customize) the TypeAhead module, use the following steps:

  1. Open the file DefaultModuleSettings.js for editing: <SmartHub website root>>modules>SmartHubResourceLoader>DefaultModuleSettings.js.
    Note: Do not modify DefaultModuleSettings.js.
    This file is overwritten at upgrade time    .

  2. Copy the TypeAhead settings you want to use from DefaultModuleSettings.js into the settings file associated with the page on your SmartHub site you want the settings to apply to.
    1. See How to Customize Your SmartHub User Interface

Example: Add PeopleSuggestions to your Landing Page (Index.html)

For example, to enable possible people matches to the text entered into the query field on your SmartHub Index page:

  1. Open the file DefaultModuleSettings.js for editing: <SmartHub website root>>modules>SmartHubResourceLoader>DefaultModuleSettings.js.

  2. Open your modified Index settings file, (named, for example, CustomIndexSettings.js) in an editor such as Notepad++.
    1. For more information on using custom settings files, see How to Customize Your SmartHub User Interface.
    2. The default custom index settings file is stored at <SmartHub website root>> CustomerCustomization\settings.

  3. Copy some or all (as you desire) of the PeopleSuggestions module code, shown below, which starts at line 234:

  4. Paste the code into your (custom) Index settings file in the brackets in the section " TypeAhead: {} ", currently around line 8. 
    See the graphic below:

    Note: In this procedure you insert code into your (custom) Index settings file, to be loaded by the SmartHub Index page, Index.html, when SmartHub is launched.

    If you want the same (or customized) settings on your Results HTML page, you must also insert TypeAhead settings code into your (custom) Results settings file in the brackets in the section " TypeAhead: {} ", currently around line 8.


     

  5. Modify the settings as you desire.

  6. Save and close all SmartHub files open in your editor.

  7. Start or refresh your SmartHub site.

TypeAhead Parameters

Use this table to modify the TypeAhead settings you include in your custom settings files (such as a custom index settings file) from the file DefaultModuleSettings.js:

Parameter Description
SuggestionsContainerParentSelector This is the CSS class of the DOM element (usually the search box) that appears above the suggestions box.
SearchBoxInputSelector

This is the css class of the DOM element that contains the search text.

TypeAhead extracts the current query text from this element.
GetSuggestionsEventName

This is the name of the event triggered by TypeAhead when requesting suggestions.

Each provider subscribes to this event and uses the provided callback to return suggestions to TypeAhead.
SuggestionsContainerClass This is the CSS class of the DOM element that holds each section.
SuggestionsItemSelectedClass This is the CSS class that is applied to the selected suggestion (using up/down arrows).
KeyPressDelay This is the time in milliseconds that TypeAhead waits before triggering the get suggestions event (after the search box text is changed).
Providers

This is an array of strings that lists the provider names that TypeAhead loads.

  • Use this parameter to exclude /include providers. In other words, by default all providers are included.
  • If you specify any providers, the specified providers are included and all other providers are excluded.
  • Notes: The associated section will still be rendered.

The provider code is located in modules > TypeAhead > Providers > <provider name> > <provider name>.js.
SuggestionsBoxMaxHeight

This is the maximum height of the suggestion box.

If the suggestion box needs to re-size over this max height, a vertical scroll bar appears.

GridHorizontalCellNumber

and

GridVerticalCellNumber

The number of cells in the suggestions box.

These settings do not modify the width or height of the suggestion box.

These settings affect the suggestion box resolution.
SectionSizes A map from the section name to an object that describes its bounds:
  • row and col: These are the y and x grid coordinates of the top left corner of the section.
  • width and height: These are the number of cells that the section spans.
ActiveProviders

Lists the providers that are active on the page.

Add a new provider to this set (via custom settings file) if you want it to be active on the page. 
ProviderSettings Maps the name of each provider to their settings object

How to Add a New Suggestions Provider

All TypeAhead providers are listed in the directory <SmartHub_install_dir>\modules\TypeAhead\Providers:

By default, some providers are listed, but not active, in your Index, and Results custom settings file templates:

  • \CustomerCustomization\settings\IndexCopyCustomSettings.js
  • \CustomerCustomization\settings\ResultsCopyCustomSettings.js

Enable a provider by simply adding its name and path to the ActiveProviders set.

Make sure to review the GridHorizontalCellNumber and GridVerticalCellNumber to make sure you have a good layout.

Use the SampleProvider as a starting point for Custom Suggestions Providers

  1. Go to the folder modules > TypeAhead > Providers > SampleProvider.
  2. Use the file SampleProvider.js as a template to create your own custom providers. You can start by using the code inside that file.

  3. Add your new provider name and settings under the ProviderSettings section of TypeAhead via your custom settings file.

  4. If you want to change / remove or add to these settings, use the custom settings file.

How to Disable TypeAhead

Many SmartHub modules such as Document Summary, TagCloud, and HoverPanel, can be "toggled" on or off.

  • The TypeAhead component requires some configuration to be disabled.
  • Add the following code to the "Paths to Exclude" line, SH.Loader.PathsToExclude, in your custom page settings file, such as:
    • CustomIndexSettings.js

    • CustomResultsSettings.js

      Copy
      SH.Loader.PathsToExclude = [
         ["/modules/TypeAhead/TypeAhead.js"]
      ];
  • For more information on creating and using SmartHub custom settings files, see How to Customize Your SmartHub User Interface.

How to Enable "Instant Search"

"Instant Search" or "Search as you type" enables results on the page and documents from Content-By-Search to refresh whenever the user presses a key in the search box.

  • To enable this feature you modify the CoveoSearchBox component by adding the following attributes:
    • data-search-as-you-type-timeout
    • data-enable-search-as-you-type
      • The time specified in the  data-search-as-you-type-timeout attribute is in milliseconds. 
Enable Search as you type
Copy 
<div class="CoveoSearchbox" data-placeholder="Search..." data-add-scoped-search="true" data-search-as-you-type-timeout="200" data-enable-search-as-you-type="true" data-show-keep-refiners="true"></div>

How to Use KeepCurrentFilters Setting

Some TypeAhead providers can use the currently applied filters when they return results.

Only the following TypeAhead providers support this feature:

  • BotProvider
  • DocProvider
  • FilesProvider
  • PeopleSuggestions

To enable this functionality the "KeepCurrentFilters" setting must be added to the custom settings for that provider and it must be set on "true".

  • The default value for KeepCurrentFilters is false.

People Suggestions Provider settings with KeepCurrentFilters
Copy 
SH.TypeAhead.CustomSettings = {
    ProviderSettings: {
            PeopleSuggestions: {
            QueryTemplate: '{searchboxquery} FederatorBackends:"*"',
            PeopleResultSource: "b09a7990-05ea-4af9-81ef-edfab16c4e31",
            KeepCurrentFilters:true,
            SectionLabel: "People matches:",
            HideLabel: true,
            row: 4,
            col: 0,
            width: 2,
            height: 1,
            expandsVertically: true,
            expandsHorizontally: true,
            MaxNumberOfSuggestions: 4,
            TemplatePath: SH.RootLevelURL + "/modules/TypeAhead/Providers/PeopleSuggestions/template.html",
            ShowMoreButtonLabel: "Show more".toLocaleString(),
            EnableShowMoreButton: false,
            EnrichUserPictureUsingUserProfileService: true,
            ShowMoreRedirectUri: "",
            PropertyMappings: {
                UserName: "username",
                AccountName: "accountname",
                PictureUrl: "PictureUrl",
                Name: "Title",
                JobTitle: "JobTitle",
                Email: "WorkEmail",
                ClickUri: "clickUri"            
            }
        }
    }
};